# 第 2 章 Harness 心智模型：官方五层与本书文件地图

2026 年，Agent 行业收敛出一个词：Harness（工程挽具）。 据 36 氪报道，OpenAI 在 2026 年初提出 Harness Engineering 的说法；36 氪对 WorkBuddy 团队的访谈里有一段适合当全书题眼的引文——WorkBuddy 负责人在解释 Red Hat 的对比时说：「sandbox 是 subtractive（减法式）的……Harness 是 additive（叠加式）的……Sandbox constrains，Harness enables.」沙盒约束，挽具赋能。你给模型套上的一整套让能力落地的工程系统，就是 Harness。

这一章建立全书的心智模型。它回答三个问题：Harness 到底包含什么？WorkBuddy 官方怎么分层？这套分层怎么落到你能摸到的文件上？

读完本章，你应能说出五层 Harness 各自的职责，并把任意一个 WorkBuddy 功能（插件、专家、记忆、定时任务）放进对应的层。

## 2.1 为什么需要「挽具」这个词

先解决概念问题。模型本身的能力边界和它实际完成任务的能力，中间隔着一整层工程。同一个模型，接上一套设计良好的工具、上下文管理和风险拦截，能稳定交付；裸着用，连「读一下本地文件」都做不到。这个差距就是 Harness 填的。

对普通用户，这个词的价值是把你已经感知到的现象命名。「WorkBuddy 比网页版 ChatGPT 能干活」——你现在可以说：两者模型能力可能相当，差距在 Harness。「装了某插件后 WorkBuddy 变笨了」——那是 Harness 的拼装层被塞进了低质量内容。命名之后，问题才可分析。

WorkBuddy 团队的工程复盘长文给出了官方的五层划分。以下每层的职责描述来自该文，本地文件对应列是本书的实测补充——这张对照表是全书的总纲。

## 2.2 官方五层模型

**第一层：运行环境层——Agent 在哪里执行。** 文件系统、Shell、沙箱、浏览器、MCP 与连接器、权限边界。这一层决定 Agent 的手脚能伸到哪里。本地对应：沙箱配置与写路径白名单（settings.json）、连接器目录、自带的语言运行时（binaries/ 下的 node 和 python）。

**第二层：引导层——Agent 开始前掌握什么。** 项目上下文、环境信息、规则与风格、技能、提示词缓存结构。任务开始前给足前置条件，模型就不用「盲人摸象」式探索。本地对应：系统提示词模板（第 5 章）、身份四件套（第 6 章）、技能目录（第 9 章）、规则文件。

**第三层：反馈层——执行后如何获知错误。** 可纠正的工具返回、时间戳校验、lint 与测试信号、审计日志。Agent 不怕报错，怕的是得不到报错。本地对应：会话文件里的工具结果事件、按天滚动的审计日志、文件历史快照。

**第四层：编排层——多个能力如何组织。** 渐进式加载、意图识别、多模型路由、团队协作、并行调用。当任务超过单循环能力，这层负责拆与合。本地对应：专家团工具入口（第 7 章）、技能的按需加载机制（第 9 章）、产品配置里的模型路由。

**第五层：迭代层——Harness 自身如何演进。** 这层不在磁盘上，在团队的迭代节奏里：随模型能力涨落精简或加码约束。据 36 氪报道，WorkBuddy 三个多月发了 43 个版本，平均不到两天一版；更新日志里「专家提示词不再注入身份文件」「工作空间自动创建记忆文件」这类条目，就是 Harness 在自我调整的证据。本书冻结的 5.3.13，是这条河流的一帧。

![官方五层 Harness 与本地证据对照](/workbuddy-harness/fig-02.png)

*图 2-1：官方五层 Harness 与本地证据对照。*

## 2.3 把五层当索引用

五层模型的用法不是背诵，是当检索框架。遇到任何 WorkBuddy 行为，先问它属于哪层：

- 「它怎么会记得我上周说过的话」→ 引导层（记忆注入，第 4 章）。
- 「为什么删文件要确认」→ 运行环境层（权限模式，第 12 章）。
- 「专家团和普通对话有什么区别」→ 编排层（第 7 章）。
- 「它说改了但我找不到改动」→ 反馈层（会话与审计，第 10 章）。
- 「升级后行为变了」→ 迭代层（版本 diff，附录 D 的取证方法）。

这个框架也解释了本书为什么按现在的顺序组织：第 3 章先给全景地图，然后从引导层（记忆、提示词、身份）讲到编排层（专家、插件、技能），再回到运行环境层与反馈层（安全、证据），最后实战。

## 2.4 五层×本书章节对照总表

把官方五层、本地证据与本书章节放进一张总表，作为全书导航的收束：

| Harness 层 | 职责一句话 | 本地证据位置 | 本书章节 |
|-|-|-|-|
| 运行环境层 | 手脚伸到哪 | 沙箱白名单、权限审批、连接器、自带运行时 | 第 11、12 章 |
| 引导层 | 开始前知道什么 | 提示词模板、身份四件套、技能、规则文件 | 第 4、5、6、9 章 |
| 反馈层 | 做错了怎么知道 | 工具报错回传、审计日志、文件快照 | 第 10 章 |
| 编排层 | 多能力怎么组织 | 专家与专家团、渐进加载、模型路由 | 第 7、8 章 |
| 迭代层 | 系统自己怎么进化 | 更新日志的机制条目时间线 | 附录 D、第 13 章 13.1 |

这张表也是读后自测的工具：合上书，任选一层，你能说出它的三个本地文件证据吗？说不出的那层，就是值得重读的部分。

## 2.5 一个容易混淆的区分：Harness 与模型

最后一个心智校准。用户报告「WorkBuddy 不好用」时，原因可能在模型（能力不足）、也可能在 Harness（上下文拼装不当、工具配置错、记忆污染）。两者的修复路径完全不同：前者换模型或拆解任务，后者改配置、清记忆、调插件。

判断归属的第一步，是看证据（第 10 章的方法）：会话文件里模型是否拿到了正确的上下文？工具调用是否被拦截？回答质量差但输入正确，多半是模型问题；该有的记忆没出现在请求里，是 Harness 问题。**把「AI 不行」翻译成「哪一层不行」，是从用户变成驾驭者的分界线**。

本书余下部分都在这张地图上行动。下一章，我们推开 `~/.workbuddy` 的大门。